home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / ab20 / ab20_archive / languages / assembly / powervisor_113.lzh / docs / Debug < prev    next >
Text File  |  1992-02-13  |  49KB  |  1,095 lines
  1. *-----------------*
  2. * Tutorial: Debug * Thu Feb 13 21:27:56 1992
  3. *-----------------*
  4.  
  5. ===================== Commands used in this tutorial =========================
  6.  
  7.    break       Control breakpoints
  8.    debug       Control debug tasks
  9.    disp        Display integer
  10.    drefresh    Refresh debug display
  11.    dscroll     Scroll in debug display
  12.    dstart      Set start programcounter in debug display
  13.    duse        Set the default debug task
  14.    dwin        Open/close 'Debug' logical window
  15.    info        Ask information about a structure or node
  16.    list        List structures
  17.    loadfd      Load fd-file
  18.    prefs       Set preferences
  19.    source      Load source files for sourcelevel debugger
  20.    symbol      Control symbols
  21.    trace       Control tracing
  22.    unasm       Disassemble memory
  23.    with        Temporarily set the default debug task
  24.  
  25.  
  26. ===================== Functions used in this tutorial ========================
  27.  
  28.    botpc       Get the programcounter at the bottom of the display
  29.    toppc       Get the programcounter at the top of the display
  30.  
  31.  
  32. ============================== Introduction ==================================
  33.  
  34. I don't think that you will be surprised if I tell you that PowerVisor can
  35. even debug programs :-) This file explains how you should do this. It also
  36. explains how you can make life easier with a fully customized
  37. ²fullscreen debugger. PowerVisor is a very powerful debugger. For example,
  38. you can ³debug multiple tasks at the same time.
  39.  
  40. Note that PowerVisor is not really a ³source level debugger, although
  41. you can load the source (even for C programs). The source will also follow
  42. the current programcounter. In future I plan more support for local and
  43. global variables in C. A stack watcher would also be a nice thing.
  44.  
  45. Note that the PowerVisor debug system works much better in the AmigaDOS 2.0
  46. version. This is because AmigaDOS 2.0 has some nice features making life a
  47. lot easier for the programmer. I'm sorry for all AmigaDOS 1.3 users.
  48. The examples below work on AmigaDOS 1.3 and 2.0.
  49.  
  50.  
  51. ============================ Loading a program ===============================
  52.  
  53. There are several ways to load a program. The method you chooses depends on
  54. what you really need. The 'debug' command is provided by PowerVisor to
  55. control the ²debug tasks (or debug nodes). All the ²debug nodes can be found
  56. in the ²'dbug' list. With the 'debug' command you can load a program, you can
  57. unload a program and you can do other things as well.
  58.  
  59.  
  60. =========================== An example session ===============================
  61.  
  62. This section contains a complete example debugging session. Note that we
  63. do not use the ²fullscreen debugger in this example. Use of the fullscreen
  64. debugger is explained later. It is recommended that you type each command
  65. as it appears here. Note that the output given here assumes that you have
  66. all preferences set to default values (use 'mode shex', 'prefs dmode f' and
  67. 'prefs debug 5 1' if you are not sure that the default values are used).
  68.  
  69.  
  70. -------------------------- Starting the session ------------------------------
  71.  
  72. 'debug n' is the recommended way to load a program. 'debug n' waits for
  73. the next program that is started and interrupts it before the first
  74. instruction is executed. To do this, 'debug n' patches the Dos ¹LoadSeg
  75. function. Example :
  76.  
  77. < debug n <enter>
  78.  
  79. PowerVisor waits for you to start the program you want to debug. You
  80. can start this program from the ¹WorkBench (click on the icon) or you
  81. can start it from the Cli or Shell. I have provided an example program
  82. with a ²resident breakpoint. Resident breakpoints are explained later
  83. in this file. You can find this program in the ²'Examples' subdirectory.
  84.  
  85. CLI< examples/buggyprogram <enter>
  86. or
  87. CLI< run examples/buggyprogram <enter>
  88.  
  89. (Note ! Only use 'run' when 'run' is ¹resident or a built-in shell command,
  90. in other words: don't use 'run' when 'run' itself must be loaded from disk
  91. with 'loadseg'. You probably don't want to debug 'run' :-) 'run' is always
  92. resident in AmigaDOS 2.0)
  93.  
  94. (Note ! When PowerVisor is waiting for a program you must be careful not
  95. to use any other program (that is already running) that might use LoadSeg
  96. for some other purpose. Fonts, for example, are loaded using LoadSeg)
  97.  
  98. (Note ! You can ¹interrupt 'debug n' with ¹<esc>)
  99.  
  100. 'debug n' is the best way to load a debug task because the program runs
  101. in exactly the same environment as the environment you get when you simply
  102. run the program.
  103.  
  104. Allright, we have now loaded the program in memory.
  105.  
  106. < list dbug <enter>
  107. > Debug task          : Node     Task     InitPC   TD ID Mode  SMode TMode
  108. > ---------------------------------------------------------------------------
  109. > Background CLI      : 07EA7A58 07EF8FA8 07EAA7D8 FF FF NONE  WAIT  NORM
  110.  
  111. Most of this information is rather technical and is not very interesting at
  112. this moment. 'InitPC' is interesting though. Let's try :
  113.  
  114. < u 07EAA7D8 <enter>
  115. or
  116. < unasm 07EAA7D8 <enter>
  117.  
  118. > 07EAA7D8: 7200                          MOVEQ.L  #0,D1
  119. > 07EAA7DA: 7064                          MOVEQ.L  #$64,D0
  120. > 07EAA7DC: 5281                          ADDQ.L   #1,D1
  121. > 07EAA7DE: 51C8 FFFC                     DBF      D0,$7EAA7DC
  122. > 07EAA7E2: 6100 0010                     BSR      $7EAA7F4
  123. > 07EAA7E6: 6708                          BEQ      $7EAA7F0
  124. > 07EAA7E8: 6100 0022                     BSR      $7EAA80C
  125. > 07EAA7EC: 6100 0046                     BSR      $7EAA834
  126. > 07EAA7F0: 7000                          MOVEQ.L  #0,D0
  127. > 07EAA7F2: 4E75                          RTS
  128. > 07EAA7F4: 203C 0000 0064                MOVE.L   #$64,D0
  129. > 07EAA7FA: 7200                          MOVEQ.L  #0,D1
  130. > 07EAA7FC: 2C78 0004                     MOVEA.L  (4),A6
  131. > 07EAA800: 4EAE FF3A                     JSR      ($FF3A,A6)
  132. > 07EAA804: 41FA 0042                     LEA      ($7EAA848,PC),A0
  133. > 07EAA808: 2080                          MOVE.L   D0,(A0)
  134. > 07EAA80A: 4E75                          RTS
  135. > 07EAA80C: 7000                          MOVEQ.L  #0,D0
  136. > 07EAA80E: 7201                          MOVEQ.L  #1,D1
  137. > 07EAA810: 7402                          MOVEQ.L  #2,D2
  138.  
  139. Well, this is our program. But there are ²symbol hunks in our program.
  140. 'debug n' does not automatically load them ('debug l' does, but this command
  141. will be explained later). You can ²load symbols with the 'symbol' command :
  142.  
  143. < symbol l examples/buggyprogram <enter>
  144.  
  145. < u 07EAA7D8 <enter>
  146. > StartProgr7200                          MOVEQ.L  #0,D1
  147. > 07EAA7DA: 7064                          MOVEQ.L  #$64,D0
  148. > loop      5281                          ADDQ.L   #1,D1
  149. > 07EAA7DE: 51C8 FFFC                     DBF      D0,loop
  150. > 07EAA7E2: 6100 0010                     BSR      Sub1
  151. > 07EAA7E6: 6708                          BEQ      theend
  152. > 07EAA7E8: 6100 0022                     BSR      Sub2
  153. > 07EAA7EC: 6100 0046                     BSR      Sub3
  154. > theend    7000                          MOVEQ.L  #0,D0
  155. > 07EAA7F2: 4E75                          RTS
  156. > Sub1      203C 0000 0064                MOVE.L   #$64,D0
  157. > 07EAA7FA: 7200                          MOVEQ.L  #0,D1
  158. > 07EAA7FC: 2C78 0004                     MOVEA.L  (4),A6
  159. > 07EAA800: 4EAE FF3A                     JSR      ($FF3A,A6)
  160. > 07EAA804: 41FA 0042                     LEA      (Block,PC),A0
  161. > 07EAA808: 2080                          MOVE.L   D0,(A0)
  162. > 07EAA80A: 4E75                          RTS
  163. > Sub2      7000                          MOVEQ.L  #0,D0
  164. > 07EAA80E: 7201                          MOVEQ.L  #1,D1
  165. > 07EAA810: 7402                          MOVEQ.L  #2,D2
  166.  
  167. You can ³show all symbols with the 'symbol' command :
  168.  
  169. < symbol s <enter>
  170. > StartProgram                             : 07EAA7D8 , 132818904
  171. > loop                                     : 07EAA7DC , 132818908
  172. > theend                                   : 07EAA7F0 , 132818928
  173. > Sub1                                     : 07EAA7F4 , 132818932
  174. > Sub2                                     : 07EAA80C , 132818956
  175. > Sub3                                     : 07EAA834 , 132818996
  176. > Block                                    : 07EAA848 , 132819016
  177.  
  178. The two values on the right of each symbol are the same. The only difference
  179. is that the left one is ¹hexadecimal and the right one is ¹decimal.
  180.  
  181. Because we have loaded the symbols for the current debug task we can use the
  182. symbols in ¹expressions. Here are some examples :
  183.  
  184. Disassemble 5 instructions starting with 'StartProgram' (note that symbols
  185. are case sensitive) :
  186.  
  187. < u StartProgram 5 <enter>
  188. > StartProgr7200                          MOVEQ.L  #0,D1
  189. > 07EAA7DA: 7064                          MOVEQ.L  #$64,D0
  190. > loop      5281                          ADDQ.L   #1,D1
  191. > 07EAA7DE: 51C8 FFFC                     DBF      D0,loop
  192. > 07EAA7E2: 6100 0010                     BSR      Sub1
  193.  
  194. Show the distance between subroutine 2 and subroutine 1 :
  195.  
  196. < d Sub2-Sub1 <enter>
  197. > 00000018,24
  198.  
  199. You can do many other things with the 'symbol' command but 'symbol l' and
  200. 'symbol s' are sufficient at this moment.
  201.  
  202. There is still one thing we should do :
  203.  
  204. < loadfd exec fd:exec_lib.fd <enter>
  205.  
  206. With this command PowerVisor loads all the ³library function definitions in
  207. memory. That way PowerVisor will know how to show a ²library function when
  208. one is encountered while ¹tracing. You do not have to load ¹fd-files, but
  209. it is certainly very easy. I have the four big fd-files ('exec.library',
  210. 'graphics.library', 'intuition.library' and 'dos.library') permanently
  211. loaded in memory (I have put four 'loadfd' commands in the
  212. ¹s:PowerVisor-startup file).
  213.  
  214.  
  215. ----------------------------------Tracing ------------------------------------
  216.  
  217. Now we can start tracing :
  218.  
  219. < trace i <enter>
  220. or
  221. < tr i <enter>
  222. > ---------------------------------------------------------------------------
  223. > D0: 00000001   D1: 01FAA9F5   D2: 00002EE0   D3: 07ED3A1C
  224. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  225. > A0: 07ED3A1C   A1: 07EF9D28   A2: 07E0CEA4   A3: 07EAA7D4
  226. > A4: 07EFCC00   A5: 00F906DE   A6: 00F906D2
  227. > PC: 07EAA7D8   SP: 07EFCBFC   SR: 0010
  228. > 00000000: 0000 0000                     ORI.B    #0,D0
  229. >
  230. > StartProgr7200                          MOVEQ.L  #0,D1
  231. > 07EAA7DA: 7064                          MOVEQ.L  #$64,D0
  232. > loop      5281                          ADDQ.L   #1,D1
  233. > 07EAA7DE: 51C8 FFFC                     DBF      D0,loop
  234. > 07EAA7E2: 6100 0010                     BSR      Sub1
  235.  
  236. (tr i : give 'I'nformation)
  237. This command shows where we are. No actual tracing is done. The registers
  238. are shown and the five first instructions. The program counter points to the
  239. second instruction in this output. The first instruction is always equal to
  240. the previous executed instruction. Initially it is initialized to address 0.
  241. Note that you can change the format of this output with the 'prefs dmode'
  242. and 'prefs debug' commands (See the 'InstallingPowerVisor' file).
  243.  
  244. Now we are really going to trace one instruction :
  245.  
  246. < tr <enter>
  247. > ---------------------------------------------------------------------------
  248. > D0: 00000001   D1: 00000000   D2: 00002EE0   D3: 07ED3A1C
  249. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  250. > A0: 07ED3A1C   A1: 07EF9D28   A2: 07E0CEA4   A3: 07EAA7D4
  251. > A4: 07EFCC00   A5: 00F906DE   A6: 00F906D2
  252. > PC: 07EAA7DA   SP: 07EFCBFC   SR: 0014
  253. > StartProgr7200                          MOVEQ.L  #0,D1
  254. >
  255. > 07EAA7DA: 7064                          MOVEQ.L  #$64,D0
  256. > loop      5281                          ADDQ.L   #1,D1
  257. > 07EAA7DE: 51C8 FFFC                     DBF      D0,loop
  258. > 07EAA7E2: 6100 0010                     BSR      Sub1
  259. > 07EAA7E6: 6708                          BEQ      theend
  260.  
  261. In the register display you can see that 'd1' now has the value 0.
  262. 'StartProgr' is now the previous instruction. The programcounter now points
  263. to the instruction 'moveq.l #$64,d0'.
  264.  
  265. Trace six instructions at once :
  266.  
  267. < tr n 6 <enter>
  268. > ---------------------------------------------------------------------------
  269. > D0: 00000062   D1: 00000003   D2: 00002EE0   D3: 07ED3A1C
  270. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  271. > A0: 07ED3A1C   A1: 07EF9D28   A2: 07E0CEA4   A3: 07EAA7D4
  272. > A4: 07EFCC00   A5: 00F906DE   A6: 00F906D2
  273. > PC: 07EAA7DE   SP: 07EFCBFC   SR: 0000
  274. > loop      5281                          ADDQ.L   #1,D1
  275. >
  276. > 07EAA7DE: 51C8 FFFC                     DBF      D0,loop
  277. > 07EAA7E2: 6100 0010                     BSR      Sub1
  278. > 07EAA7E6: 6708                          BEQ      theend
  279. > 07EAA7E8: 6100 0022                     BSR      Sub2
  280. > 07EAA7EC: 6100 0046                     BSR      Sub3
  281.  
  282. (tr n : trace 'N'umber instruction)
  283. We are now in the loop.
  284.  
  285. To ²step over the loop we can use the following instruction :
  286.  
  287. < tr o <enter>
  288. > ---------------------------------------------------------------------------
  289. > D0: 0000FFFF   D1: 00000065   D2: 00002EE0   D3: 07ED3A1C
  290. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  291. > A0: 07ED3A1C   A1: 07EF9D28   A2: 07E0CEA4   A3: 07EAA7D4
  292. > A4: 07EFCC00   A5: 00F906DE   A6: 00F906D2
  293. > PC: 07EAA7E2   SP: 07EFCBFC   SR: 0000
  294. > 07EAA7DE: 51C8 FFFC                     DBF      D0,loop
  295. >
  296. > 07EAA7E2: 6100 0010                     BSR      Sub1
  297. > 07EAA7E6: 6708                          BEQ      theend
  298. > 07EAA7E8: 6100 0022                     BSR      Sub2
  299. > 07EAA7EC: 6100 0046                     BSR      Sub3
  300. > theend    7000                          MOVEQ.L  #0,D0
  301. > Breakpoint...
  302.  
  303. (tr o : trace 'O'ver)
  304. 'tr o' places a ¹breakpoint after the current instruction and then executes
  305. until the breakpoint is encountered. You can trace over every instruction
  306. with this command, but you can't use it in ¹ROM-code since PowerVisor can't
  307. put a ³breakpoint in ROM (don't worry ! there are solutions to this problem,
  308. we will see them later on).
  309.  
  310. We step into the subroutine 'Sub1' with :
  311.  
  312. < tr <enter>
  313. > ---------------------------------------------------------------------------
  314. > D0: 0000FFFF   D1: 00000065   D2: 00002EE0   D3: 07ED3A1C
  315. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  316. > A0: 07ED3A1C   A1: 07EF9D28   A2: 07E0CEA4   A3: 07EAA7D4
  317. > A4: 07EFCC00   A5: 00F906DE   A6: 00F906D2
  318. > PC: 07EAA7F4   SP: 07EFCBF8   SR: 0000
  319. > 07EAA7E2: 6100 0010                     BSR      Sub1
  320. >
  321. > Sub1      203C 0000 0064                MOVE.L   #$64,D0
  322. > 07EAA7FA: 7200                          MOVEQ.L  #0,D1
  323. > 07EAA7FC: 2C78 0004                     MOVEA.L  (4),A6
  324. > 07EAA800: 4EAE FF3A                     JSR      ($FF3A,A6)
  325. > 07EAA804: 41FA 0042                     LEA      (Block,PC),A0
  326.  
  327. Trace another three instructions :
  328.  
  329. < tr n 3 <enter>
  330. > ---------------------------------------------------------------------------
  331. > D0: 00000064   D1: 00000000   D2: 00002EE0   D3: 07ED3A1C
  332. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  333. > A0: 07ED3A1C   A1: 07EF9D28   A2: 07E0CEA4   A3: 07EAA7D4
  334. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  335. > PC: 07EAA800   SP: 07EFCBF8   SR: 0004
  336. > 07EAA7FC: 2C78 0004                     MOVEA.L  (4),A6
  337. >
  338. > 07EAA800: 4EAE FF3A                     JSR      (AllocMem,A6)
  339. > 07EAA804: 41FA 0042                     LEA      (Block,PC),A0
  340. > 07EAA808: 2080                          MOVE.L   D0,(A0)
  341. > 07EAA80A: 4E75                          RTS
  342. > Sub2      7000                          MOVEQ.L  #0,D0
  343.  
  344. Thanks to the loaded fd-file you can now see that this function is actually
  345. the Exec AllocMem. We do not want to run through the complete rom function
  346. so we ²trace over the call with :
  347.  
  348. < tr t <enter>
  349. > ---------------------------------------------------------------------------
  350. > D0: 07EFCE90   D1: 00002F48   D2: 00002EE0   D3: 07ED3A1C
  351. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  352. > A0: 07E00000   A1: 07EFCE90   A2: 07E0CEA4   A3: 07EAA7D4
  353. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  354. > PC: 07EAA804   SP: 07EFCBF8   SR: 0010
  355. > 07EAA800: 4EAE FF3A                     JSR      ($FF3A,A6)
  356. >
  357. > 07EAA804: 41FA 0042                     LEA      (Block,PC),A0
  358. > 07EAA808: 2080                          MOVE.L   D0,(A0)
  359. > 07EAA80A: 4E75                          RTS
  360. > Sub2      7000                          MOVEQ.L  #0,D0
  361. > 07EAA80E: 7201                          MOVEQ.L  #1,D1
  362. > Breakpoint...
  363.  
  364. (tr t : 'T'race over BSR or JSR      sorry, couldn't find a better character)
  365. 'tr t' looks similar to 'tr o'. The big difference is that 'tr t' works only
  366. for 'BSR' and 'JSR' instructions. And what is more important : 'tr t' works
  367. in ¹ROM-code. If 'tr t' is used for an instruction other than 'BSR' or 'JSR'
  368. it is analogous to 'tr' (simple singlestep).
  369.  
  370. We can see that the AllocMem function had success (I hope this is really the
  371. case) because 'd0' contains the address of the newly allocated memory.
  372.  
  373. We continue tracing until the next ³change of program flow happens :
  374.  
  375. < tr b <enter>
  376. > ---------------------------------------------------------------------------
  377. > D0: 07EFCE90   D1: 00002F48   D2: 00002EE0   D3: 07ED3A1C
  378. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  379. > A0: 07EAA848   A1: 07EFCE90   A2: 07E0CEA4   A3: 07EAA7D4
  380. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  381. > PC: 07EAA80A   SP: 07EFCBF8   SR: 0010
  382. > 07EAA808: 2080                          MOVE.L   D0,(A0)
  383. >
  384. > 07EAA80A: 4E75                          RTS
  385. > Sub2      7000                          MOVEQ.L  #0,D0
  386. > 07EAA80E: 7201                          MOVEQ.L  #1,D1
  387. > 07EAA810: 7402                          MOVEQ.L  #2,D2
  388. > 07EAA812: 7603                          MOVEQ.L  #3,D3
  389.  
  390. (tr b : trace until 'B'ranch)
  391. 'tr b' traces until a change of program control happens. This means that
  392. tracing will stop always at the following instructions :
  393.    JMP
  394.    JSR
  395.    BRA
  396.    BSR
  397.    RTE
  398.    RTD
  399.    RTR
  400.    RTS
  401.    TRAP
  402. and tracing will stop at the following instructions if the brach would
  403. succeed :
  404.    Bcc
  405.    DBcc
  406.  
  407. Go out this subroutine :
  408.  
  409. < tr <enter>
  410. > ---------------------------------------------------------------------------
  411. > D0: 07EFCE90   D1: 00002F48   D2: 00002EE0   D3: 07ED3A1C
  412. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  413. > A0: 07EAA848   A1: 07EFCE90   A2: 07E0CEA4   A3: 07EAA7D4
  414. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  415. > PC: 07EAA7E6   SP: 07EFCBFC   SR: 0010
  416. > 07EAA80A: 4E75                          RTS
  417. >
  418. > 07EAA7E6: 6708                          BEQ      theend
  419. > 07EAA7E8: 6100 0022                     BSR      Sub2
  420. > 07EAA7EC: 6100 0046                     BSR      Sub3
  421. > theend    7000                          MOVEQ.L  #0,D0
  422. > 07EAA7F2: 4E75                          RTS
  423.  
  424. < tr <enter>
  425. > ---------------------------------------------------------------------------
  426. > D0: 07EFCE90   D1: 00002F48   D2: 00002EE0   D3: 07ED3A1C
  427. > D4: 00000001   D5: 00000001   D6: 01FAA08F   D7: 07EAA7D4
  428. > A0: 07EAA848   A1: 07EFCE90   A2: 07E0CEA4   A3: 07EAA7D4
  429. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  430. > PC: 07EAA7E8   SP: 07EFCBFC   SR: 0010
  431. > 07EAA7E6: 6708                          BEQ      theend
  432. >
  433. > 07EAA7E8: 6100 0022                     BSR      Sub2
  434. > 07EAA7EC: 6100 0046                     BSR      Sub3
  435. > theend    7000                          MOVEQ.L  #0,D0
  436. > 07EAA7F2: 4E75                          RTS
  437. > Sub1      203C 0000 0064                MOVE.L   #$64,D0
  438.  
  439. We suspect nothing bad in 'Sub2' so we simply trace over it :
  440.  
  441. < tr t <enter>
  442. > ---------------------------------------------------------------------------
  443. > D0: 00000000   D1: 00000001   D2: 00000002   D3: 00000003
  444. > D4: 00000004   D5: 00000005   D6: 00000006   D7: 00000007
  445. > A0: 07EFCE90   A1: 07EFCE90   A2: 07E0CEA4   A3: 07EAA7D4
  446. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  447. > PC: 07EAA820   SP: 07EFCBF8   SR: 0010
  448. > 07EAA7E8: 6100 0022                     BSR      Sub2
  449. >
  450. > 07EAA820: 4AFC                          ILLEGAL
  451. > 07EAA822: 20C0                          MOVE.L   D0,(A0)+
  452. > 07EAA824: 20C1                          MOVE.L   D1,(A0)+
  453. > 07EAA826: 20C2                          MOVE.L   D2,(A0)+
  454. > 07EAA828: 20C3                          MOVE.L   D3,(A0)+
  455. > Illegal instruction !
  456.  
  457. There is something wrong ! This is called a ²²resident breakpoint. You can
  458. put resident breakpoints in a program using the ²'ILLEGAL' instruction.
  459. PowerVisor will automatically stop at such places.
  460.  
  461. ²Skip over the instruction with :
  462.  
  463. < tr s <enter>
  464. > ---------------------------------------------------------------------------
  465. > D0: 00000000   D1: 00000001   D2: 00000002   D3: 00000003
  466. > D4: 00000004   D5: 00000005   D6: 00000006   D7: 00000007
  467. > A0: 07EFCE90   A1: 07EFCE90   A2: 07E0CEA4   A3: 07EAA7D4
  468. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  469. > PC: 07EAA820   SP: 07EFCBF8   SR: 0010
  470. > 07EAA820: 4AFC                          ILLEGAL
  471. >
  472. > 07EAA822: 20C0                          MOVE.L   D0,(A0)+
  473. > 07EAA824: 20C1                          MOVE.L   D1,(A0)+
  474. > 07EAA826: 20C2                          MOVE.L   D2,(A0)+
  475. > 07EAA828: 20C3                          MOVE.L   D3,(A0)+
  476. > 07EAA82A: 20C4                          MOVE.L   D4,(A0)+
  477.  
  478. ('tr s' : 'S'kip instruction)
  479. Now we have something special. Since we used the 'tr t' command to trace
  480. over the subroutine 'Sub2' we have created a breakpoint after the 'BSR Sub2'
  481. instruction. But if we would look after the 'BSR Sub2' instruction we
  482. would find no breakpoint (we will see later how PowerVisor shows breakpoints
  483. in the disassembly display). This is because the 'tr t' command works in
  484. a special way to make sure that you can use it in ROM-code too. Here follows
  485. an explanation of what has happened :
  486.  
  487.       You typed 'tr t' when to skip 'BSR Sub2' a time ago.
  488.       PowerVisor performs a 'tr' to trace the 'BSR' instruction.
  489.       Now the top of the stack contains the returnaddress for the 'BSR'
  490.       instruction, this is the address of the instruction after 'BSR Sub2'.
  491.       PowerVisor replaces the address on the stack with another address.
  492.       This address points to a ²private breakpoint. Since this private
  493.       breakpoint is always in RAM, there is no problem setting this
  494.       breakpoint. When the subroutine returns (with 'RTS') later on (this
  495.       has not happened at this moment), it will not return to the instruction
  496.       after the 'BSR' but to the breakpoint in RAM. PowerVisor will trap this
  497.       and set the programcounter of the task to the right address: this is
  498.       the instruction after the 'BSR Sub2'.
  499.  
  500.       It would be different if you hade used 'tr o' instead of 'tr t'. 'tr o'
  501.       would put a breakpoint directly after the 'BSR Sub2'. This will
  502.       ofcourse not work if the 'BSR' is in ROM since a breakpoint is in fact
  503.       an ILLEGAL instruction.
  504.  
  505. But since the routine 'Sub2' was interrupted (the 'ILLEGAL' instruction
  506. caused this). The private breakpoint has not been encountered yet and
  507. the value on the stack is still the wrong value. We can make use of this
  508. feature and simply continue the 'tr t' where it left of with :
  509.  
  510. < tr g <enter>
  511. > ---------------------------------------------------------------------------
  512. > D0: 00000000   D1: 00000001   D2: 00000002   D3: 00000003
  513. > D4: 00000004   D5: 00000005   D6: 00000006   D7: 00000007
  514. > A0: 07EFCEB0   A1: 07EFCE90   A2: 07E0CEA4   A3: 07EAA7D4
  515. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  516. > PC: 07EAA7EC   SP: 07EFCBFC   SR: 0010
  517. > 07EAA822: 20C0                          MOVE.L   D0,(A0)+
  518. >
  519. > 07EAA7EC: 6100 0046                     BSR      Sub3
  520. > theend    7000                          MOVEQ.L  #0,D0
  521. > 07EAA7F2: 4E75                          RTS
  522. > Sub1      203C 0000 0064                MOVE.L   #$64,D0
  523. > 07EAA7FA: 7200                          MOVEQ.L  #0,D1
  524. > Breakpoint...
  525.  
  526. ('tr g' : trace 'G'o)
  527. The 'tr g' command simply executes the program until a breakpoint is
  528. encountered.
  529. Note that it would make no difference if you would trace the program step
  530. by step. At one moment you would encounter the ²private breakpoint. Simply
  531. tracing over this breakpoint will return to the correct place in the
  532. program.
  533.  
  534. We step into 'Sub3' :
  535.  
  536. < tr <enter>
  537. > ---------------------------------------------------------------------------
  538. > D0: 00000000   D1: 00000001   D2: 00000002   D3: 00000003
  539. > D4: 00000004   D5: 00000005   D6: 00000006   D7: 00000007
  540. > A0: 07EFCEB0   A1: 07EFCE90   A2: 07E0CEA4   A3: 07EAA7D4
  541. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  542. > PC: 07EAA834   SP: 07EFCBF8   SR: 0010
  543. > 07EAA7EC: 6100 0046                     BSR      Sub3
  544. >
  545. > Sub3      203C 0000 0040                MOVE.L   #$40,D0
  546. > 07EAA83A: 227A 000C                     MOVEA.L  (Block,PC),A1
  547. > 07EAA83E: 2C78 0004                     MOVEA.L  (4),A6
  548. > 07EAA842: 4EAE FF2E                     JSR      ($FF2E,A6)
  549. > 07EAA846: 4E75                          RTS
  550.  
  551. < tr <enter>
  552. > ---------------------------------------------------------------------------
  553. > D0: 00000040   D1: 00000001   D2: 00000002   D3: 00000003
  554. > D4: 00000004   D5: 00000005   D6: 00000006   D7: 00000007
  555. > A0: 07EFCEB0   A1: 07EFCE90   A2: 07E0CEA4   A3: 07EAA7D4
  556. > A4: 07EFCC00   A5: 00F906DE   A6: 07E007D8
  557. > PC: 07EAA83A   SP: 07EFCBF8   SR: 0010
  558. > Sub3      203C 0000 0040                MOVE.L   #$40,D0
  559. >
  560. > 07EAA83A: 227A 000C                     MOVEA.L  (Block,PC),A1
  561. > 07EAA83E: 2C78 0004                     MOVEA.L  (4),A6
  562. > 07EAA842: 4EAE FF2E                     JSR      ($FF2E,A6)
  563. > 07EAA846: 4E75                          RTS
  564. > Block     07EF CE90                     BSET     D3,($CE90,A7)
  565.  
  566. We see that something is wrong. We have allocated 100 bytes of memory
  567. ($64) but we are only going to free 64 bytes ($40). This is clearly
  568. a bug and should be fixed. But to prevent memoryloss we are going to
  569. continue anyway. We simply change the 'd0' ¹register :
  570.  
  571. < d @d0 <enter>
  572. > 00000040,64
  573.  
  574. < @d0=100 <enter>
  575.  
  576. You see how we can look at registers and change their values.
  577.  
  578. We are not interested in the rest of the program. We simply let it go :
  579.  
  580. < tr g <enter>
  581. > Program quits !
  582.  
  583. The program has stopped.
  584.  
  585. Some important 'trace' commands have been explained. There are a lot more.
  586. Some of the other 'trace' commands will be used in the following example.
  587. You have to refer to the online help or to the 'CommandReference' file for
  588. the other features.
  589.  
  590.  
  591. ============================ Example session 2 ===============================
  592.  
  593. I have prepared another program so you can see the power of PowerVisor.
  594. With this example we are going to make you used to breakpoints and some
  595. other advanced features of the 'trace' command. We are also going to use
  596. the ²²fullscreen debugger (Note that I will explain later how you can
  597. customize this fullscreen debugger to your wishes and how you can use
  598. the 'db' script to do this for you).
  599.  
  600.  
  601. -------------------------- Starting the session ------------------------------
  602.  
  603. We are now going to load the program using 'debug l'. Normally this is
  604. not the recommended way since this instruction does not perfectly emulate
  605. a ¹Cli or ¹WorkBench.  But this does not matter for our little program.
  606. Note that the AmigaDOS 2.0 version of PowerVisor perfectly creates a CLI,
  607. so 'debug l' is a very good way to load a program if you have AmigaDOS 2.0.
  608.  
  609. < debug l examples/buggyprogram2 <enter>
  610.  
  611. The symbols are automatically loaded by 'debug l' :
  612.  
  613. < symbol s <enter>
  614. > StartProgram                             : 07EADCC0 , 132832448
  615. > Long                                     : 07EADCCE , 132832462
  616. > recur                                    : 07EADCE0 , 132832480
  617. > theend                                   : 07EADCEC , 132832492
  618.  
  619. Open the fullscreen debugger display :
  620.  
  621. < dwin <enter>
  622. < prefs dmode n <enter>
  623.  
  624. The 'prefs dmode' command is used to disable the output on the 'Main'
  625. logical window you normally get after each trace. All the output goes
  626. automatically to the 'Debug' logical window if it is open (but if you
  627. set 'prefs dmode f' as it is default you will get output in the 'Debug'
  628. logical window AND on the 'Main' logical window. This is probably not
  629. as intended).
  630.  
  631. Drag the ²horizontal bar between the ³'Main' logical window and the
  632. ³'Debug' logical window until all the five instructions of the disassembly
  633. are visible.
  634.  
  635. The following ¹keys can be used :
  636.       <ctrl>+<NumPad Up>      to decrease the top visible instruction address
  637.                               with 2
  638.       <ctrl>+<NumPad Down>    to increase this address with 2
  639.       <ctrl>+<NumPad PgUp>    to decrease this address with 20
  640.       <ctrl>+<NumPad PgDn>    to increase this address with 20
  641.       <ctrl>+<NumPad 5>       to set this address equal to the programcounter
  642. Using this keys you can ¹scroll through your code (try it).
  643.  
  644. Press :
  645.  
  646. < <ctrl>+<NumPad 5>
  647.  
  648. To go back to the programcounter.
  649. (Note that you can also use the 'dscroll' and 'dstart' commands to scroll
  650. through your program, see the 'CommandReference' file)
  651.  
  652. The fullscreen debugger display looks almost the same as the output from
  653. the 'trace' command in the earlier section. The differences are :
  654.  
  655.    - There is an indicator of what the task is doing.
  656.          NONE     the task is waiting for PowerVisor instructions
  657.          TRACE    the task is tracing
  658.          EXEC     the task is executing
  659.    - The top instruction (except for the previous instruction indicator)
  660.      is not always equal to the instruction at the ¹programcounter. The
  661.      programcounter is indicated by ²hilighted line.
  662.    - The ²previous instruction is only updated when the programcounter makes
  663.      a jump out of the current displayed instructions.
  664.  
  665.  
  666. ------------------------------- Breakpoints ----------------------------------
  667.  
  668. First a simple ¹¹breakpoint :
  669.  
  670. Lets put a breakpoint in the 'Long' subroutine.
  671.  
  672. < u Long <enter>
  673. > Long      7000                          MOVEQ.L  #0,D0
  674. > 07EADCD0: 7201                          MOVEQ.L  #1,D1
  675. > 07EADCD2: 7402                          MOVEQ.L  #2,D2
  676. > 07EADCD4: 7603                          MOVEQ.L  #3,D3
  677. > 07EADCD6: 7804                          MOVEQ.L  #4,D4
  678. > 07EADCD8: 7A05                          MOVEQ.L  #5,D5
  679. > 07EADCDA: 7C06                          MOVEQ.L  #6,D6
  680. > 07EADCDC: 7E07                          MOVEQ.L  #7,D7
  681. > 07EADCDE: 4E75                          RTS
  682. > recur     5280                          ADDQ.L   #1,D0
  683. > 07EADCE2: 0C80 0000 00C8                CMPI.L   #$C8,D0
  684. > 07EADCE8: 6E02                          BGT      theend
  685. > 07EADCEA: 61F4                          BSR      recur
  686. > theend    4E75                          RTS
  687. > 07EADCEE: 0000 07EA                     ORI.B    #$EA,D0
  688. > 07EADCF2: DD08                          ADDX.B   -(A0),-(A6)
  689. > 07EADCF4: 0000 0000                     ORI.B    #0,D0
  690. > 07EADCF8: 07E2                          BSET     D3,-(A2)
  691. > 07EADCFA: 68A0                          BVC      $7EADC9C
  692. > 07EADCFC: 0002 004C                     ORI.B    #$4C,D2
  693.  
  694. < break n 07EADCD2 <enter>       (Note ! Use the equivalent address!)
  695. or
  696. < b n 07EADCD2 <enter>
  697.  
  698. > 00000001,1
  699.  
  700. ('b n' : 'N'ormal breakpoint)
  701. The output from this command is the breakpoint number. PowerVisor can have
  702. as many breakpoints as memory permits. Breakpoints are always refered to
  703. with their number.
  704.  
  705. With the 'info' command you can now ask more information about the
  706. breakpoints :
  707.  
  708. < l dbug <enter>
  709. > Debug task          : Node     Task     InitPC   TD ID Mode  SMode TMode
  710. > ---------------------------------------------------------------------------
  711. > examples/buggyprogra: 07EADB90 07ED5840 07EADCC0 FF FF NONE  WAIT  NORM
  712.  
  713. < info dbug:'examples/buggyprogram2' dbug <enter>
  714. or
  715. < i db:examp db <enter>
  716.  
  717. > Debug task          : Node     Task     InitPC   TD ID Mode  SMode TMode
  718. > ---------------------------------------------------------------------------
  719. > examples/buggyprogra: 07EADB90 07ED5840 07EADCC0 FF FF NONE  WAIT  NORM
  720. >
  721. > Node     Number Where    UsageCnt Type Condition
  722. > ---------------------------------------------------------------------------
  723. > 07EBA168     1  07EADCD2        0   N
  724.  
  725. We can see that there is one breakpoint defined with number 1 and position
  726. 07EA77DA. It has not been used yet and it is a normal (N) breakpoint.
  727. ('Condition' is explained later).
  728.  
  729. Lets have a look at the disassembly :
  730.  
  731. < u Long 20 <enter>
  732. > Long      7000                          MOVEQ.L  #0,D0
  733. > 07EADCD0: 7201                          MOVEQ.L  #1,D1
  734. > 07EADCD2: 4AFC                          MOVEQ.L  #2,D2  >1
  735. > 07EADCD4: 7603                          MOVEQ.L  #3,D3
  736. > 07EADCD6: 7804                          MOVEQ.L  #4,D4
  737. > 07EADCD8: 7A05                          MOVEQ.L  #5,D5
  738. > 07EADCDA: 7C06                          MOVEQ.L  #6,D6
  739. > 07EADCDC: 7E07                          MOVEQ.L  #7,D7
  740. > 07EADCDE: 4E75                          RTS
  741. > recur     5280                          ADDQ.L   #1,D0
  742. > 07EADCE2: 0C80 0000 00C8                CMPI.L   #$C8,D0
  743. > 07EADCE8: 6E02                          BGT      theend
  744. > 07EADCEA: 61F4                          BSR      recur
  745. > theend    4E75                          RTS
  746. > 07EADCEE: 0000 07EA                     ORI.B    #$EA,D0
  747. > 07EADCF2: DD08                          ADDX.B   -(A0),-(A6)
  748. > 07EADCF4: 0000 0000                     ORI.B    #0,D0
  749. > 07EADCF8: 07E2                          BSET     D3,-(A2)
  750. > 07EADCFA: 68A0                          BVC      $7EADC9C
  751. > 07EADCFC: 0002 004C                     ORI.B    #$4C,D2
  752.  
  753. The breakpoint is the instruction with the '>1' appended.
  754.  
  755. Now we start the program and see where it ends :
  756.  
  757. < tr g <enter>
  758. > Breakpoint...
  759.  
  760. (Notice that we no longer get the complete output on 'Main'. All output
  761. is in the 'Debug' logical window)
  762.  
  763. The breakpoint has been encountered. Since it is a normal breakpoint it
  764. is not removed.
  765.  
  766. < i db:examp db <enter>
  767. > Debug task          : Node     Task     InitPC   TD ID Mode  SMode TMode
  768. > ---------------------------------------------------------------------------
  769. > examples/buggyprogra: 07EADB90 07ED5840 07EADCC0 FF FF NONE  WAIT  NORM
  770. >
  771. > Node     Number Where    UsageCnt Type Condition
  772. > ---------------------------------------------------------------------------
  773. > 07EBA168     1  07EADCD2        1   N
  774.  
  775. Now we see that the ²usage counter has incremented.
  776.  
  777. We make two new breakpoints :
  778.  
  779. < b t 07EADCDA <enter>
  780.  
  781. < b c recur '@d0==100' <enter>
  782.  
  783. < i db:exam db <enter>
  784. > Debug task          : Node     Task     InitPC   TD ID Mode  SMode TMode
  785. > ---------------------------------------------------------------------------
  786. > examples/buggyprogra: 07EADB90 07ED5840 07EADCC0 FF FF NONE  WAIT  STEP
  787. >
  788. > Node     Number Where    UsageCnt Type Condition
  789. > ---------------------------------------------------------------------------
  790. > 07EBA288     3  07EADCE0        0   C  @d0==100
  791. > 07EB5B60     2  07EADCDA        0   T
  792. > 07EBA168     1  07EADCD2        1   N
  793.  
  794. ('b t' : 'T'emporary breakpoint)
  795. ('b c' : 'C'onditional breakpoint)
  796. 'b t' makes a ²temporary breakpoint. This is a breakpoint that only breaks
  797. once. 'b c' makes a conditional breakpoint. ²Conditional breakpoints are
  798. very powerful as you will see in the following demonstration.
  799.  
  800. < tr g <enter>
  801. > Breakpoint...
  802.  
  803. The breakpoint breaks and is immediatelly removed.
  804.  
  805. < tr g <enter>
  806. > Breakpoint...
  807.  
  808. The conditional breakpoint breaks because 'd0' is equal to 100. A conditional
  809. breakpoint is a very powerful way to control your program. The breakpoint
  810. condition can be as complex as you wish (with the exception that you can't
  811. use the ²group operator) and you can refer to all ¹registers like @pc, @sr,
  812. @sp, @d0 to @d7 and @a0 to @a6.
  813.  
  814. We ³remove the breakpoint with :
  815.  
  816. < b r 3 <enter>
  817.  
  818. ('b r' : 'R'emove breakpoint)
  819.  
  820. Now we are going to put a breakpoint just after the 'BSR' instruction :
  821.  
  822. < u StartProgram <enter>
  823. > StartProgr6100 000C                     BSR      Long
  824. > 07EADCC4: 7000                          MOVEQ.L  #0,D0
  825. > 07EADCC6: 6100 0018                     BSR      recur
  826. > 07EADCCA: 7000                          MOVEQ.L  #0,D0
  827. > 07EADCCC: 4E75                          RTS
  828. > Long      7000                          MOVEQ.L  #0,D0
  829. > 07EADCD0: 7201                          MOVEQ.L  #1,D1
  830. > 07EADCD2: 4AFC                          MOVEQ.L  #2,D2  >1
  831. > 07EADCD4: 7603                          MOVEQ.L  #3,D3
  832. > 07EADCD6: 7804                          MOVEQ.L  #4,D4
  833. > 07EADCD8: 7A05                          MOVEQ.L  #5,D5
  834. > 07EADCDA: 7C06                          MOVEQ.L  #6,D6
  835. > 07EADCDC: 7E07                          MOVEQ.L  #7,D7
  836. > 07EADCDE: 4E75                          RTS
  837. > recur     5280                          ADDQ.L   #1,D0
  838. > 07EADCE2: 0C80 0000 00C8                CMPI.L   #$C8,D0
  839. > 07EADCE8: 6E02                          BGT      theend
  840. > 07EADCEA: 61F4                          BSR      recur
  841. > theend    4E75                          RTS
  842. > 07EADCEE: 0000 07EA                     ORI.B    #$EA,D0
  843.  
  844. We see that there is still another breakpoint present in the 'Long'
  845. subroutine. Remove it with :
  846.  
  847. < b r 1 <enter>
  848.  
  849. We make the new breakpoint :
  850.  
  851. < b n 07EADCCA <enter>
  852. > 00000001,1
  853.  
  854. Now we execute until we reach that breakpoint :
  855.  
  856. < tr g <enter>
  857. > Breakpoint...
  858.  
  859. And we start all over again by setting the programcounter back to the
  860. start of the program :
  861.  
  862. < @pc=StartProgram <enter>
  863.  
  864. Now we are ready to demonstrate yet another powerful feature which looks a
  865. bit like conditional breakpoints : ²conditional tracing.
  866.  
  867. < tr c '@d0==100' <enter>
  868.  
  869. ('tr c' : 'C'onditional tracing)
  870. 'tr c' singlesteps the program until the condition is true. The difference
  871. with the conditional breakpoint is that the breakpoint only checks the
  872. condition when the breakpoint is passed. With conditional tracing the
  873. condition is checked after each instruction. Conditional tracing is ofcourse
  874. much slower.
  875.  
  876. Remove the debug task from memory with :
  877.  
  878. < debug u <enter>
  879.  
  880. This command removes all breakpoints and unloads the program. It is best
  881. to always use this command in conjunction with 'debug l'. You can also
  882. use 'debug r' to remove all breakpoints and stop debugging. After 'debug r'
  883. the debug program will simply continue as if nothing has happened. This
  884. has two disadvantages : It is possible that the program is buggy and will
  885. crash. In that case it is not wise to use 'debug r'. PowerVisor will also
  886. not be able to unload the program from memory. This means that you
  887. will loose some memory (you == your Amiga :-)
  888. 'debug r' is more useful in conjunction with the 'debug n' command (and
  889. also with the 'debug c' command which can be used to catch a task).
  890. You can also use 'debug f' (see the 'CommandReference' file for more
  891. info).
  892.  
  893. Close the debug logical window with :
  894.  
  895. < dwin <enter>
  896.  
  897.  
  898. =============================== Some theory ==================================
  899.  
  900. When you issue a trace command to PowerVisor, the 'trace' command will return
  901. immediatelly. This means that when the trace could take a long time, you will
  902. still be able to use PowerVisor for other commands. For example, when you are
  903. tracing conditionally, PowerVisor will do absolutely nothing. The debug task
  904. does everything until the condition becomes true. The debug task will then
  905. send a signal to PowerVisor and PowerVisor will update the debug display.
  906.  
  907. The conditional trace command is one of the trace commands that uses
  908. ²singlestep mode for tracing. This is slow but sometimes the only way to
  909. trace something. The 'go' trace command ('tr g') is another trace command.
  910. This trace command uses ²execute mode for tracing. The task runs at full
  911. speed until a breakpoint is encountered. It is possible that you want
  912. singlestep mode for the 'tr g' command too. For example, you could use this
  913. to see how a program runs. Since the program runs a bit slower you will be
  914. able to see much better what happens at each step. To use singlestep mode
  915. with the 'tr g' command you must use 'tr gt' ('t' for trace). Most tracing
  916. commands have these two versions.
  917.  
  918. Note that you can ³interrupt the tracing if you like with 'tr h' or
  919. 'tr f'.
  920.  
  921. Some commands (like 'tr u' and 'tr o' (explained later)) make a private
  922. breakpoint. A ²private breakpoint is a breakpoint with number 0. This
  923. breakpoint is automatically cleared when another breakpoint with number 0
  924. is about to be created, or when the breakpoint breaks.
  925.  
  926.  
  927. ========================== Resident breakpoints ==============================
  928.  
  929. You can set ²²resident breakpoints in your programs by including an 'ILLEGAL'
  930. instruction at the right place. When you want to use them you must make sure
  931. that PowerVisor is started and that you use 'mode patch'. Otherwise the
  932. results will not be very satisfactory. After that you simply start your
  933. program (from the 'Shell' or 'Workbench') (Note ! Don't use 'debug n'
  934. in PowerVisor). When the program collides with the resident breakpoint,
  935. PowerVisor will ³trap the crash. You have now made a ²crash node. You can
  936. than use 'debug t' with the crash node or with the crashed task to
  937. start debugging at the 'ILLEGAL' instruction.
  938.  
  939.  
  940. =========================== The fdebug command ===============================
  941.  
  942. To make life easier s/PowerVisor-startup defines an alias that you can
  943. use to initialize the fullscreen debugger. This alias uses the 'db'
  944. script to open the debug logical window and to initialize some
  945. keys. See the 'Aliases' reference file for more information about the
  946. 'fdebug' alias.
  947.  
  948.  
  949. ========================== sourcelevel debugging =============================
  950.  
  951. If you want you can load the source for the debug task you are tracing.
  952. PowerVisor will automatically follow this source, even when you switch
  953. to a routine in another file. See the 'Source' command in the
  954. 'CommandReference' file for more information.
  955.  
  956.  
  957. =========================== The other commands ===============================
  958.  
  959. Here follows a summary of what you can do with all debug commands :
  960.  
  961.    break n <address>    Set 'N'ormal breakpoint.
  962.                         The breakpoint is not removed after breaking
  963.    break t <address>    Set 'T'emporary breakpoint.
  964.                         The breakpoint is removed after breaking
  965.    break p <address>    Set 'P'rofile breakpoint
  966.                         This breakpoint never breaks. It only increments
  967.                         the usagecounter. You can use it to see if a
  968.                         certain routine is much used
  969.    break a <address> <timeout>
  970.                         Break 'A'fter <timeout> passes.
  971.                         The breakpoint is removed after breaking
  972.    break c <address> <condition>
  973.                         'C'onditional breakpoint. This breakpoint breaks when
  974.                         the condition is true. The breakpoint is not removed
  975.                         after breaking
  976.    break r <breakpoint number>
  977.                         Remove a breakpoint
  978.    debug n              Wait for 'N'ext prorgram
  979.    debug c              Wait for next task
  980.    debug l <filename>   'L'oad a program and load symbols
  981.                         This command also creates a CLI structure if you
  982.                         use the AmigaDOS 2.0 version of PowerVisor
  983.    debug t <task>|<crash node>
  984.                         Take an existing task or crash node and make
  985.                         a debug node for it. With this command you can
  986.                         in theory debug any task in the system (be
  987.                         careful though)
  988.    debug f              Remove the current debug node and freeze the
  989.                         debug task
  990.    debug f <debug node> Remove the specified debug node and freeze the
  991.                         corresponding task. Use this command if you are
  992.                         debugging multiple programs at the same time.
  993.                         You can find all debug nodes in the 'dbug' list
  994.    debug r              Remove the current debug node. The debug task
  995.                         will continue executing at the programcounter
  996.    debug r <debug node> Remove the specified debug node
  997.    debug u              Remove the current debug node. The debug task
  998.                         will be stopped and the program will be unloaded.
  999.    debug u <debug node> Same as 'debug u' but for a specified debug node.
  1000.    debug d <name>       Create a ³dummy debug node with name <name>.
  1001.                         You can't use this node for debugging but you
  1002.                         can use it to create ¹symbols
  1003.    drefresh             Refresh the ²debug display
  1004.    dscroll <offset>     Scroll <offset> bytes up in the fullscreen debugger.
  1005.                         Negative values are allowed. <offset> will be made
  1006.                         a multiple of two.
  1007.    dstart <address>     Set the start of the debug logical window.
  1008.    duse <debug node>    Set the default debug node. This is useful when
  1009.                         you are debugging multiple tasks at the same time.
  1010.    dwin                 Open/Close 'Debug' logical window
  1011.    symbol l <filename> [<hunkaddress>]
  1012.                         ³Load the symbols for the current debug task.
  1013.                         If you give <hunkaddress>, PowerVisor will load the
  1014.                         symbols for the given ¹hunks. This is extremely
  1015.                         useful when you have created a ³dummy debug task.
  1016.                         Note that <hunkaddress> is 4 more than the number
  1017.                         given in the hunklist with the 'hunks' command.
  1018.                         Note that <hunkaddress> is not optional when you are
  1019.                         loading symbols for a dummy debug task.
  1020.    symbol c             Clear all symbols for the current debug node
  1021.    symbol a <symbolname> <value>
  1022.                         Add a symbol to the list of symbols
  1023.    symbol r <symbolname>
  1024.                         Remove a symbol from the list of symbols
  1025.    symbol s             List all symbols for the current debug node
  1026.    source l <filename> [<hunkaddress>]
  1027.                         ³Load the source for the current debug task.
  1028.                         If you give <hunkaddress>, PowerVisor will load the
  1029.                         source for the given ¹hunks. This is extremely
  1030.                         useful when you have created a ³dummy debug task.
  1031.                         Note that <hunkaddress> is 4 more than the number
  1032.                         given in the hunklist with the 'hunks' command.
  1033.                         Note that <hunkaddress> is not optional when you
  1034.                         are loading the source for a dummy debug task
  1035.    source w <address>   Use this command to see in which source file and
  1036.                         on which line a specific address is located
  1037.    source t <tab size>  Set the tab size used for the source display. The
  1038.                         default tab value is 8
  1039.    source s             Show all sources for the current debug task
  1040.    source r             Redisplay the source in the 'Source' logical window
  1041.    source c             Clear all sources and unload them
  1042.    source g <line>      Move the source to a specific line
  1043.    trace                Trace one instruction (singlestep mode)
  1044.    trace n <number>     Trace <number> instructions (singlestep mode)
  1045.    trace b              Trace until the next change of program flow
  1046.                         (singlestep mode)
  1047.    trace t              Trace over JSR or BSR. IF the instruction is
  1048.                         not a BSR or JSR this command is analogous to
  1049.                         'trace' (execute mode)
  1050.    trace j              Trace until a library ROM function is about
  1051.                         to be called with JMP ...(a6) or JSR ...(a6).
  1052.                         (singlestep mode)
  1053.    trace r <register>   Trace until a specified register is changed.
  1054.                         Register can be d0-d7, a0-a6 or sp.
  1055.                         (singlestep mode)
  1056.    trace u <address>    Trace until programcounter is equal to <address>.
  1057.                         This command works by setting a private
  1058.                         breakpoint (number 0) at <address>. This command
  1059.                         only works when <address> is not in ROM
  1060.                         (execute mode)
  1061.    trace ut <address>   Trace until programcounter is equal to <address>.
  1062.                         No breakpoint is set by this command. <address>
  1063.                         can be in ROM
  1064.                         (singlestep mode)
  1065.    trace o              Trace over the current instruction. This command
  1066.                         is analogous to 'trace u' with <address> equal
  1067.                         to the instruction following the current instruction
  1068.                         (execute mode)
  1069.    trace ot             Trace over the current instruction.
  1070.                         This version can be used in ROM
  1071.                         (singlestep mode)
  1072.    trace c <condition>  Trace until <condition> is true
  1073.                         (singlestep mode)
  1074.    trace s              Skip instruction
  1075.    trace i              Do not trace. Show the current registers and
  1076.                         instructions (obsolete in the fullscreen debugger)
  1077.    trace g              Trace until a breakpoint is encountered (note that
  1078.                         all previous trace commands also stop when a
  1079.                         breakpoint is encountered)
  1080.                         (execute mode)
  1081.    trace gt             Trace until a breakpoint is encountered
  1082.                         (singlestep mode)
  1083.    trace h              Interrupt the tracing or executing of the
  1084.                         current debug task
  1085.    trace f              Interrupt the tracing or executing of the
  1086.                         current debug task as soon as this task
  1087.                         is in ready state
  1088.    with <debug node> <command>
  1089.                         Temporarily set the current debug node and execute
  1090.                         <command>. This is useful for example, if you are
  1091.                         debugging with multiple programs at the same time and
  1092.                         you want to have a look at the symbols or registers
  1093.                         of the other program
  1094.  
  1095.